package cn.dwy2002.binaryhandwritingserver.service.service;


import cn.dwy2002.binaryhandwritingserver.common.Result;
import cn.dwy2002.binaryhandwritingserver.exception.TagNotFoundException;
import cn.dwy2002.binaryhandwritingserver.pojo.po.Tags;
import cn.dwy2002.binaryhandwritingserver.pojo.vo.TagsVO;

import java.util.List;

/**
 * @author 杜伟毅
 * @version 1.0
 * @since 2025/05/29
 */
public interface TagService {
    /**
     * 创建新标签
     *
     * @param tag 标签对象（无需包含ID）
     * @return 创建成功的标签对象（包含生成的ID）
     */
    Result<Void> createTag(Tags tag);

    /**
     * 更新标签信息
     *
     * @param tag 标签对象（必须包含有效ID）
     * @return 更新后的标签对象
     * @throws TagNotFoundException 标签不存在时抛出
     */
    Result<Void> updateTag(Tags tag) throws TagNotFoundException;

    /**
     * 删除标签
     *
     * @param id 标签ID
     * @throws TagNotFoundException 标签不存在时抛出
     */
    Result<Void> deleteTag(Long id) throws TagNotFoundException;

    /**
     * 获取标签详情
     *
     * @param id 标签ID
     * @return 标签对象
     * @throws TagNotFoundException 标签不存在时抛出
     */
    Result<TagsVO> getTagById(Long id) throws TagNotFoundException;

    /**
     * 获取所有标签
     *
     * @return 标签列表（无标签时返回空列表）
     */
    List<TagsVO> getAllTags();

    /**
     * 根据名称获取标签
     *
     * @param name 标签名称
     * @return 标签对象
     */
    Result<TagsVO> getTagByName(String name);
}
